gitlab.com/SiaPrime/SiaPrime@v1.4.1/doc/Running and Writing Tests for SiaPrime.md

# Running and Writing Tests for SiaPrime
Improving test coverage is a great way to start contributing to SiaPrime.  

This guide focuses on how to write tests. You should also read
[doc/Developers.md][developers] to learn about SiaPrime code conventions and 
quality standards.


#### Table of Contents
- [Running and Writing Tests for SiaPrime](#Running-and-Writing-Tests-for-SiaPrime)
			- [Table of Contents](#Table-of-Contents)
	- [Running tests for SiaPrime](#Running-tests-for-SiaPrime)
		- [Updating code before testing](#Updating-code-before-testing)
		- [Testing the entire build](#Testing-the-entire-build)
		- [Testing a particular package or function](#Testing-a-particular-package-or-function)
	- [Writing new tests for SiaPrime](#Writing-new-tests-for-SiaPrime)
		- [A few guidelines](#A-few-guidelines)
		- [Basic test format](#Basic-test-format)
		- [Table-driven tests in Go](#Table-driven-tests-in-Go)
		- [SiaPrimetest Package](#SiaPrimetest-Package)
	- [Questions?](#Questions)

<a name="existing"></a>
## Running tests for SiaPrime
Go's comprehensive [test package][pkg/testing] makes testing straightforward,
particularly when you use the bundled tools included in the
[SiaPrime makefile][makefile], including `make test`, `make cover`, `make bench`,
and their variants.

<a name="update"></a>
### Updating code before testing
If you just want to run existing tests on the codebase as is, you just need to
pull the latest version of the original repo to your master branch.

```bash
# Make sure you are in the right directory.
$ cd $GOPATH/src/github.com/<your Github username>/SiaPrime
# Also make sure you're working with the right branch.
$ git checkout master
# Pull latest changes from origin, the original SiaPrime repo. 
$ git pull origin master
# Update your fork of the repo, which should be set up as a remote.
$ git push <remote>  master
```

If you want to run tests on the new code you've added, first make sure the rest
of the code is up to date. New code should be on its own branch.

```bash
# Make sure you are in the right directory.
$ cd $GOPATH/src/github.com/<your Github username>/SiaPrime
# Checkout the branch you made the changes on.
$ git checkout <branch name>
# Stash any tracked but uncommitted changes.
$ git stash
# Then switch back to `master` and update it to match the original repo.
$ git checkout master
$ git pull origin master
# Update your fork of the repo, which you should have set up as a remote.
$ git push <remote>  master
# Make the updated `master` the new base of the branch you made the changes on,
# which involves reapplying all the commits made to that branch.  Without the
# `--ignore-date` flag, git rebase changes the date on all the commits to the
# current date.
$ git checkout <branch name>
$ git rebase master --ignore-date
# Restore the changes you stashed earlier.
$ git stash pop
```
When you call `rebase`, you may run into some merge conflicts.  Luke Champine's
['How to into git and GitHub'][luke] has more details (and many useful tricks).

Once the branch you want to test is up to date, you're ready to run some tests.

<a name="entire"></a>
### Testing the entire build
The `make test` command runs all tests (functions starting with `Test` in
`_test.go` files) for each package, setting off a panic for any test that runs
longer than 5s.  For verbose output, run `make test-v` (which panics after 15s
instead of 5s).  Finally, `make test-long` has verbose output, only panics when
a test takes 5 minutes, and also cleans up your code using `gofmt` and `golint`. 
**You should run** `make test-long` **before each pull request.**

Run `make cover` to run all tests for each package and generate color-coded
.html visualizations of test coverage by function for each source file.  Open
`cover/<module>.html` in a browser to inspect a module's test coverage. For 
example, here's part of the html file generated for the persist package: 

![Screenshot](assets/covertool.png)

Meanwhile, `make bench` will call `gofmt` on all packages, then run all
benchmarks (functions starting with `Benchmark` in `_test.go` files).

<a name="particular"></a>
### Testing a particular package or function
To run tests for just a certain package, run `make test pkgs=./<package>`. To run 
a certain test function, run `make test pkgs=./<package> run=<function>`. The same
goes for `make test-long`, `make cover` and `make bench`.

For example, running `test-long` on the package persist produces this output:

```bash
$ make test-long pkgs=./persist
rm -rf release doc/whitepaper.aux doc/whitepaper.log doc/whitepaper.pdf
gofmt -s -l -w ./persist
go install ./persist
go vet ./persist
go test -v -race -tags='testing debug' -timeout=300s ./persist -run=Test
=== RUN   TestOpenDatabase
--- PASS: TestOpenDatabase (0.42s)
=== RUN   TestSaveLoad
--- PASS: TestSaveLoad (0.00s)
=== RUN   TestSaveLoadFile
--- PASS: TestSaveLoadFile (0.01s)
=== RUN   TestSaveLoadFileSync
--- PASS: TestSaveLoadFileSync (0.00s)
=== RUN   TestLogger
--- PASS: TestLogger (0.00s)
=== RUN   TestLoggerCritical
--- PASS: TestLoggerCritical (0.00s)
=== RUN   TestIntegrationRandomSuffix
--- PASS: TestIntegrationRandomSuffix (0.01s)
=== RUN   TestAbsolutePathSafeFile
--- PASS: TestAbsolutePathSafeFile (0.00s)
=== RUN   TestRelativePathSafeFile
--- PASS: TestRelativePathSafeFile (0.00s)
PASS
ok  	gitlab.com/SiaPrime/SiaPrime/persist	1.485s
$
``` 

<a name="write"></a>
## Writing new tests for SiaPrime
When you run `make cover`, you'll notice that many files have pretty low
coverage.  We're working on fixing that, but we could use your help.

<a name="naming"></a>
### A few guidelines
* The test functions for `filename.go` should go in `filename_test.go` in the
    same directory and package.
* A test function name should start with `Test` and clearly convey what is
    being tested.
* You should declare function-specific variables and constants locally (inside
    the test function) instead of globally (outside the test function).  [That 
	holds in general][global], not just for tests.
* As always, code should adhere to the standards and conventions laid out in
    [doc/Developers.md][developers].
* If a test interacts with the disk it should be skipped during the short tests
  by including the following at the beginning of the test:
  ```go
  if testing.Short() {
	  t.SkipNow()
  }
  ```

<a name="basic"></a>
### Basic test format
Suppose we'd like to test the Bar method belonging to type Foo.  

```go
// TestFoo checks that the Bar method on type Foo responds correctly to a normal
// input and returns the expected error when given a bad input.
func TestFoo(t *testing.T) {
	foo, err := NewFoo()
	if err != nil {
	// If NewFoo failed, we can't continue testing.
	t.Fatal(err)
	}

	// Try a normal input; should succeed.
	err := foo.Bar(3)
	if err != nil {
		// Report the error, but don't abort the test.
		t.Error(err)
	}

	// Try a bad input; should return an error.
	// NOTE: Always prefer to compare to a specific error, rather than 
	// err == nil
	err = Foo.Bar(0)
	if err != errDivideByZero {
		t.Errorf("expected errDivideByZero, got %v", err)
	}
}

```

<a name="table"></a>
### Table-driven tests in Go
If you're looking to test a bunch of inputs, write a [table-driven test][table]
with a slice of anonymous structs. For example, see `TestParseFileSize` in 
[spc/parse_test.go][parse_test]:

```go
func TestParseFilesize(t *testing.T) {
	// Define a table of test cases in the form of a slice of anonymous structs.
	tests := []struct {
		in, out string
		err     error
	}{
		{"1b", "1", nil},
		{"1KB", "1000", nil},
		{"1MB", "1000000", nil},
		{"1GB", "1000000000", nil},
		{"1TB", "1000000000000", nil},
		{"1KiB", "1024", nil},
		{"1MiB", "1048576", nil},
		{"1GiB", "1073741824", nil},
		{"1TiB", "1099511627776", nil},
		{"", "", errUnableToParseSize},
		{"123", "123", nil},
		{"123TB", "123000000000000", nil},
		{"123GiB", "132070244352", nil},
		{"123BiB", "", errUnableToParseSize},
		{"GB", "", errUnableToParseSize},
		{"123G", "", errUnableToParseSize},
		{"123B99", "", errUnableToParseSize},
		{"12A3456", "", errUnableToParseSize},
		{"1.23KB", "1230", nil},
		{"1.234KB", "1234", nil},
		{"1.2345KB", "1234", nil},
	}
	// Loop through the table of test cases to make sure ParseFileSize returns 
	// the expected output and error for each.
	for _, test := range tests {
		res, err := parseFilesize(test.in)
		if res != test.out || err != test.err {
			t.Errorf("parseFilesize(%v): expected %v %v, got %v %v", test.in, test.out, test.err, res, err)
		}
	}
}
```

<a name="siaPrimetest">
### SiaPrimetest Package
When deciding what tests to write for SiaPrime, you should consider whether the 
best test is a unit test or a siaprimetest. Ideally both a unit test and a 
siaprimetest is written for new code. A unit test should explicitly test the new
code functionality and a siaprimetest should test the integration of the code 
and how itaffects the rest of the platform. All the tests in the siaprimetest
package should use the API to execute the test. The idea is that everything that
is trying to be tested should be able to be controlled and verified through the 
API. If you are looking for a place to start, there are many examples of older 
tests that could be upgraded to siaprimetests.

<a name="questions"></a>
## Questions?
Read these if you haven't already:
* getting started with Go 
* SiaPrime, and git
* [doc/Developers.md][developers]: conventions and quality standards for 
* SiaPrime code

Some other useful resources, some of which have been linked to already:
* [Golang.org page on the go testing package][pkg/testing]
* [Writing Table-Driven Tests in Go][table]
* [How to Write Benchmarks in Go][cheney-benchmarks]
* [How to into git and GitHub][luke]: an essential introduction to git

And feel free to ask questions on the [#development channel][discord] on the 
SiaPrime Discord. 
Odds are, someone else is wondering the same thing.

[pkg/testing]: https://golang.org/pkg/testing/
[makefile]: https://gitlab.com/SiaPrime/SiaPrime/blob/master/Makefile
[luke]: https://gist.github.com/lukechampine/6418449
[developers]: https://gitlab.com/SiaPrime/SiaPrime/blob/master/doc/Developers.md
[table]: http://dave.cheney.net/2013/06/09/writing-table-driven-tests-in-go
[boltdb_test.go]: https://gitlab.com/SiaPrime/SiaPrime/blob/master/persist/boltdb_test.go
[cheney-benchmarks]: http://dave.cheney.net/2013/06/30/how-to-write-benchmarks-in-go
[pkg/testing]: https://golang.org/pkg/testing/
[discord]: https://discord.gg/5DAgTn8
[parse_test]: https://gitlab.com/SiaPrime/SiaPrime/blob/master/spc/parse_test.go
[global]: http://c2.com/cgi/wiki?GlobalVariablesAreBad